home *** CD-ROM | disk | FTP | other *** search
/ MacHack 2000 / MacHack 2000.toast / pc / The Hacks / MacHacksBug / Python 1.5.2c1 / Tools / pynche / README < prev    next >
Encoding:
Text File  |  2000-06-23  |  13.5 KB  |  342 lines
  1. Pynche - The PYthonically Natural Color and Hue Editor
  2.  
  3. Contact: Barry A. Warsaw
  4. Email:   bwarsaw@python.org
  5. Version: 0.1
  6.  
  7. Introduction
  8.  
  9.     Pynche is a color editor based largely on a similar program that I
  10.     originally wrote back in 1987 for the Sunview window system.  That
  11.     editor was called ICE, the Interactive Color Editor.  I'd always
  12.     wanted to port this program to X but didn't feel like hacking X
  13.     and C code to do it.  Fast forward many years, to where Python +
  14.     Tkinter provides such a nice programming environment, with enough
  15.     power, that I finally buckled down and re-implemented it.  I
  16.     changed the name because these days, too many other systems have
  17.     the acronym `ICE'.
  18.  
  19.     Pynche has been tested with Python 1.5.1 using Tk 8.0.  It
  20.     probably works with Python 1.5.  I've tested it on both Solaris
  21.     2.6 and Windows NT.  There are some funky things that happen on
  22.     Windows but I think they are primarily Tk problems.  You'll want
  23.     to be sure to have Tk 8.0.3 for Windows.  Also, Pynche is very
  24.     colormap intensive, so it doesn't work very well on 8-bit graphics
  25.     cards.  I'll probably fix that in the future.
  26.  
  27.     Pynche must find a text database of colors, in the X11 format.
  28.     Pynche is distributed with an rgb.txt file from the X11R6.4
  29.     distribution for this reason, but you can use a different file
  30.     with the -d option.  The file xlicense.txt contains the license
  31.     only for rgb.txt and both files are in the X/ subdirectory.
  32.  
  33.     Pynche is pronounced `Pinch-ee'.
  34.  
  35. Running Standalone
  36.  
  37.     On Unix, start it by running the `pynche' script.  On Windows, run
  38.     pynche.pyw to inhibit the console window.  When run from the
  39.     command line, the following options are recognized:
  40.  
  41.     --database file
  42.     -d file
  43.         Alternate location of the color database file.  Without this
  44.         option, the first of /usr/openwin/lib/rgb.txt or X/rgb.txt
  45.         will be used.
  46.  
  47.     --initfile file
  48.     -i file
  49.         Alternate location of the persistent initialization file.  See 
  50.         the section on Persistency below.
  51.  
  52.     --ignore
  53.     -X
  54.         Ignore the persistent initialization file when starting up.
  55.         Pynche will still write the current option settings to the
  56.         persistent init file when it quits.
  57.  
  58.     --help
  59.     -h
  60.         Print the help message.
  61.  
  62.     initialcolor
  63.         a Tk color name or #rrggbb color spec to be used as the
  64.         initially selected color.  This overrides any color saved in
  65.         the persistent init file.  Since `#' needs to be escaped in
  66.         many shells, it is optional in the spec (e.g. #45dd1f is the
  67.         same as 45dd1f).
  68.  
  69. Running as a Modal Dialog
  70.  
  71.     Pynche can be run as a modal dialog, inside another application.
  72.     It supports the API implemented by the Tkinter standard
  73.     tkColorChooser module, with a few changes.  By importing
  74.     pyColorChooser from the Pynche package, you can run
  75.  
  76.         pyColorChooser.askcolor()
  77.  
  78.     which will popup Pynche as a modal dialog, and return the selected 
  79.     color.
  80.  
  81.     There are some UI differences when running as a modal
  82.     vs. standalone.  When running as a modal, there is no "File" menu,
  83.     but instead there are "Okay" and "Cancel" buttons.
  84.  
  85.     When "Okay" is hit, askcolor() returns the tuple
  86.  
  87.         ((r, g, b), "name")
  88.  
  89.     where r, g, and b are red, green, and blue color values
  90.     respectively (in the range 0 to 255).  "name" will be a color name
  91.     from the color database if there is an exact match, otherwise it
  92.     will be an X11 color spec of the form "#rrggbb".  Note that this
  93.     is different than tkColorChooser, which doesn't know anything
  94.     about color names.
  95.  
  96.     askcolor() supports the following optional keyword arguments:
  97.  
  98.         color
  99.             the color to set as the initial selected color
  100.  
  101.         master[*]
  102.             the master window to use as the parent of the modal
  103.             dialog.  Without this argument, pyColorChooser will create 
  104.             it's own Tkinter.Tk instance as the master.  This may not
  105.             be what you want.
  106.  
  107.         databasefile[*]
  108.             similar to the --database option, the value must be a
  109.             file name
  110.  
  111.         initfile[*]
  112.             similar to the --initfile option, the value must be a
  113.             file name
  114.  
  115.         ignore[*]
  116.             similar to the --ignore flag, the value is a boolean
  117.  
  118.         wantspec[*]
  119.             When this is true, the "name" field in the return tuple
  120.             will always be a color spec of the form "#rrggbb".  It
  121.             will not return a color name even if there is a match;
  122.             this is so pyColorChooser can exactly match the API of
  123.             tkColorChooser.
  124.  
  125.         [*] these arguments must be specified the first time
  126.         askcolor() is used and cannot be changed on subsequent calls.
  127.  
  128. The Colorstrip Window
  129.  
  130.     The top part of the main Pynche window contains the "variation
  131.     strips".  Each strip contains a number of "color chips".  The
  132.     strips always indicate the currently selected color by a highlight
  133.     rectangle around the selected color chip, with an arrow pointing
  134.     to the chip.  Each arrow has an associated number giving you the
  135.     color value along the variation's axis.  Each variation strip
  136.     shows you the colors that are reachable from the selected color by
  137.     varying just one axis of the color solid.
  138.  
  139.     For example, when the selected color is (in Red/Green/Blue
  140.     notation) 127/127/127, the Red Variations strip shows you every
  141.     color in the range 0/127/127 to 255/127/127.  Similarly for the
  142.     green and blue axes.  You can select any color by clicking on its
  143.     chip.  This will update the highlight rectangle and the arrow, as
  144.     well as other displays in Pynche.
  145.  
  146.     Click on "Update while dragging" if you want Pynche to update the
  147.     selected color while you drag along any variation strip (this will
  148.     be slower).  Click on "Hexadecimal" to display the arrow numbers
  149.     in hex.
  150.  
  151. The Proof Window
  152.  
  153.     In the lower left corner of the main window you see two larger
  154.     color chips.  The Selected chip shows you a larger version of the
  155.     color selected in the variation strips, along with its X11 color
  156.     specification.  The Nearest chip shows you the closest color in
  157.     the X11 database to the selected color, giving its X11 color name.
  158.     Clicking on the Nearest color chip selects that color.  Color
  159.     distance is calculated in the 3D space of the RGB color solid and
  160.     if more than one color name is the same distance from the selected
  161.     color, the first one found will be chosen.
  162.  
  163.     Note that there may be more than one X11 color name for the same
  164.     RGB value.  In that case, the first one found in the text database
  165.     is designated the "primary" name, and this is shown under the
  166.     Nearest chip.  The other names are "aliases" and they are visible
  167.     in other Pynche windows.
  168.  
  169. The Type-in Window
  170.  
  171.     At the lower right of the main window are three entry fields.
  172.     Here you can type numeric values for any of the three color axes.
  173.     Legal values are between 0 and 255, and these fields do not allow
  174.     you to enter illegal values.  You must hit Enter or Tab to select
  175.     the new color.
  176.  
  177.     Click on "Update while typing" if you want Pynche to select the
  178.     color on every keystroke (well, every one that produces a legal
  179.     value!)  Click on "Hexadecimal" to display and enter color values
  180.     in hex.
  181.  
  182. Other Views
  183.  
  184.     There are three secondary windows which are not displayed by
  185.     default.  You can bring these up via the "View" menu on the main
  186.     Pynche window.
  187.  
  188. The Text Window
  189.  
  190.     The "Text Window" allows you to see what effects various colors
  191.     have on the standard Tk text widget elements.  In the upper part
  192.     of the window is a plain Tk text widget and here you can edit the
  193.     text, select a region of text, etc.  Below this is a button "Track
  194.     color changes".  When this is turned on, any colors selected in
  195.     the other windows will change the text widget element specified in
  196.     the radio buttons below.  When this is turned off, text widget
  197.     elements are not affected by color selection.
  198.  
  199.     You can choose which element gets changed by color selection by
  200.     clicking on one of the radio buttons in the bottom part of this
  201.     window.  Text foreground and background affect the text in the
  202.     upper part of the window.  Selection foreground and background
  203.     affect the colors of the primary selection which is what you see
  204.     when you click the middle button (depending on window system) and
  205.     drag it through some text.
  206.  
  207.     The Insertion is the insertion cursor in the text window, where
  208.     new text will be inserted as you type.  The insertion cursor only
  209.     has a background.
  210.  
  211. The Color List Window
  212.  
  213.     The "Color List" window shows every color in the text database
  214.     (this window may take a while to come up).  In the upper part of
  215.     the window you see a scrolling list of all the color names in the
  216.     database, in alphabetical order.  Click on any color to select it.
  217.     In the bottom part of the window is displayed any aliases for the
  218.     selected color (those color names that have the same RGB value,
  219.     but were found later in the text database).  For example, find the
  220.     color "Black" and you'll see that its aliases are "gray0" and
  221.     "grey0".
  222.  
  223.     If the color has no aliases you'll see "<no aliases>" here.  If you
  224.     just want to see if a color has an alias, and do not want to select a
  225.     color when you click on it, turn off "Update on Click".
  226.  
  227.     Note that the color list is always updated when a color is selected
  228.     from the main window.  There's no way to turn this feature off.  If
  229.     the selected color has no matching color name you'll see
  230.     "<no matching color>" in the Aliases window.
  231.  
  232. The Details Window
  233.  
  234.     The "Details" window gives you more control over color selection
  235.     than just clicking on a color chip in the main window.  The row of
  236.     buttons along the top apply the specified increment and decrement
  237.     amounts to the selected color.  These delta amounts are applied to
  238.     the variation strips specified by the check boxes labeled "Move
  239.     Sliders".  Thus if just Red and Green are selected, hitting -10
  240.     will subtract 10 from the color value along the red and green
  241.     variation only.  Note the message under the checkboxes; this
  242.     indicates the primary color level being changed when more than one
  243.     slider is tied together.  For example, if Red and Green are
  244.     selected, you will be changing the Yellow level of the selected
  245.     color.
  246.  
  247.     The "At Boundary" behavior determines what happens when any color
  248.     variation hits either the lower or upper boundaries (0 or 255) as
  249.     a result of clicking on the top row buttons:
  250.  
  251.     Stop
  252.         When the increment or decrement would send any of the tied
  253.         variations out of bounds, the entire delta is discarded.
  254.  
  255.     Wrap Around
  256.         When the increment or decrement would send any of the tied
  257.         variations out of bounds, the out of bounds value is wrapped
  258.         around to the other side.  Thus if red were at 238 and +25
  259.         were clicked, red would have the value 7.
  260.  
  261.     Preseve Distance
  262.         When the increment or decrement would send any of the tied
  263.         variations out of bounds, all tied variations are wrapped as
  264.         one, so as to preserve the distance between them.  Thus if
  265.         green and blue were tied, and green was at 238 while blue was
  266.         at 223, and +25 were clicked, green would be at 15 and blue
  267.         would be at 0.
  268.  
  269.     Squash
  270.         When the increment or decrement would send any of the tied
  271.         variations out of bounds, the out of bounds variation is set
  272.         to the ceiling of 255 or floor of 0, as appropriate.  In this
  273.         way, all tied variations are squashed to one edge or the
  274.         other.
  275.  
  276.     The top row buttons have the following keyboard accelerators:
  277.  
  278.     -25 == Shift Left Arrow
  279.     -10 == Control Left Arrow
  280.      -1 == Left Arrow
  281.      +1 == Right Arrow
  282.     +10 == Control Right Arrow
  283.     +25 == Shift Right Arrow
  284.  
  285. Keyboard Accelerators
  286.  
  287.     Alt-w in any secondary window dismisses the window.  In the main
  288.     window it exits Pynche (except when running as a modal).
  289.  
  290.     Alt-q in any window exits Pynche (except when running as a modal).
  291.  
  292. Persistency
  293.  
  294.     Pynche remembers various settings of options and colors between
  295.     invocations, storing these values in a `persistent initialization
  296.     file'.  The actual location of this file is specified by the
  297.     --initfile option (see above), and defaults to ~/.pynche.
  298.  
  299.     When Pynche exits, it saves these values in the init file, and
  300.     re-reads them when it starts up.  There is no locking on this
  301.     file, so if you run multiple instances of Pynche at a time, you
  302.     will override the init file.
  303.  
  304.     The actual options stored include
  305.  
  306.     - the currently selected color
  307.  
  308.     - all settings of checkbox and radio button options in all windows
  309.  
  310.     - the contents of the text window, the current text selection and
  311.       insertion point, and all current text widget element color
  312.       settings.
  313.  
  314.     You can inhibit Pynche from reading the init file by supplying the
  315.     --ignore option on the command line.  However, you cannot suppress
  316.     the storing of the settings in the init file on Pynche exit.  If
  317.     you really want to do this, use /dev/null as the init file, using
  318.     --initfile.
  319.  
  320. To Do
  321.  
  322.     Here's a brief list of things I want to do:
  323.  
  324.     - Better support for resizing the top level windows
  325.  
  326.     - Better support on 8-bit screens
  327.  
  328.     - More output views, e.g. color solids
  329.  
  330.     - Have the notion of a `last color selected'; this may require a
  331.       new output view
  332.  
  333.     - Support setting the font in the text view
  334.  
  335.     I'm open to suggestions!
  336.  
  337.  
  338.  
  339. Local Variables:
  340. indent-tabs-mode: nil
  341. End:
  342.